3.9 [Rule] Sections

These are optional sections that describes the [Rule] content found in FDF files.

Summary

This section is similar to the [FV] section, with the a few exceptions. The INF statements are not permitted within a rules section.

Rules are used as templates, normally using variable names instead of fully qualified names, while INF statements are always are fully qualified file names.

The following list specifies the allowed variables that may be used exactly as typed:

$(WORKSPACE), $(EDK_SOURCE), $(EFI_SOURCE), $(TARGET), $(TOOL_CHAIN_TAG), $(ARCH), $(MODULE_NAME), $(OUTPUT_DIRECTORY), $(BUILD_NUMBER), $(INF_VERSION), $(NAMED_GUID), $(INF_OUTPUT)

Conditional statements may be used anywhere within this section.

Prototype

<Rules>             ::= "[Rule" <RuleArgs> "]" <EOL> <FileStatements>
<RuleArgs>          ::= "." <arch> "." <ModuleType>
                        [<TemplateName>]
<ModuleType>        ::= {<EdkComponentType>} {<Edk2ModuleType>}
<Edk2ModuleType>    ::= {"SEC"} {"PEI_CORE"} {"PEIM"} {"SMM_CORE"}
                        {"DXE_CORE"} {"DXE_DRIVER"}
                        {"DXE_SAL_DRIVER"} {"DXE_SMM_DRIVER"}
                        {"MM_CORE_STANDALONE"} {"MM_STANDALONE"}
                        {"DXE_RUNTIME_DRIVER"} {"UEFI_DRIVER"}
                        {"UEFI_APPLICATION"} {"USER_DEFINED"}
<EdkComponentType>  ::= {"LIBRARY"} {"APPLICATION"} {"AcpiTable"}
                        {"BINARY"} {"BS_DRIVER"} {"LOGO"}
                        {"Legacy16"} {"Microcode"} {"PE32_PEIM"}
                        {"RAWFILE"} {"RT_DRIVER"} {"SAL_RT_DRIVER"}
                        {"SECURITY_CORE"} {"COMBINED_PEIM_DRIVER"}
                        {"PIC_PEIM"} {"RELOCATABLE_PEIM"}
                        {"PEI_CORE"}
<TemplateName>      ::= "." <RuleUiName>
<RuleUiName>        ::= {<Word>} {"BINARY"}
<FileStatements>    ::= if (MODULE_TYPE == "SEC"
                        || MODULE_TYPE == "PEI_CORE"
                        || MODULE_TYPE == "PEIM"
                        || COMPONENT_TYPE == "PEI_CORE"
                        || COMPONENT_TYPE == "PIC_PEIM"
                        || COMPONENT_TYPE == "RELOCATABLE_PEIM"
                        || COMPONENT_TYPE == "SECURITY_CORE"
                        || COMPONENT_TYPE == "PE32_PEIM" ):
                        <TS> "FILE" <MTS> <FvType1> <Eq>
                        <FileStatement1>
                        elif (MODULE_TYPE == "DXE_CORE"
                        || MODULE_TYPE == "DXE_DRIVER"
                        || MODULE_TYPE == "DXE_SAL_DRIVER"
                        || MODULE_TYPE == "SMM_CORE"
                        || MODULE_TYPE == "MM_CORE_STANDALONE"
                        || MODULE_TYPE == "DXE_SMM_DRIVER"
                        || MODULE_TYPE == "MM_STANDALONE"
                        || MODULE_TYPE == "UEFI_DRIVER"
                        || MODULE_TYPE == "UEFI_APPLICATION"
                        || MODULE_TYPE == "USER_DEFINED"
                        || COMPONENT_TYPE == "BS_DRIVER"
                        || COMPONENT_TYPE == "COMBINED_PEIM_DRIVER"
                        || COMPONENT_TYPE == "APPLICATION"):
                        {<FileStatement2>} {<FileStatement3>}
                        elif (MODULE_TYPE == "FV_IMAGE"):
                        <FileStatement4>
                        else:
                        <TS> "FILE" <MTS> "NON_FFS_FILE" <Eq>
                        [<NamedGuid>] [<Options>] <EOL>
<FileStatement1>    ::= <NamedGuid> [<RelocFlags> <MTS>] [<Options>] <EOL>
<FileStatement2>    ::= <TS> "FILE" <MTS> <FvType2> <Eq> <NamedGuid>
                        [<Options>] <EOL>
<FileStatement3>    ::= <TS> "FILE" <MTS> "RAW" <Eq> <NamedGuid>
                        [<Options>] <EOL>
<FileStatement4>    ::= <TS> "FILE" <MTS> "FV_IMAGE" <Eq>
                        <NamedGuid> [<Options>] <EOL>
<NamedGuid>         ::= {"$(NAMED_GUID)"} {<NamedGuidOrPcd>}
<FvType1>           ::= {"SEC"} {"PEI_CORE"} {"PEIM"} {"PEI_DXE_COMBO"}
<FvType2>           ::= {"FREEFORM"} {"DRIVER"} {"DXE_CORE"}
                        {"APPLICATION"} {"SMM_CORE"} {"SMM"}
                        {"MM_CORE_STANDALONE"} {"MM_STANDALONE"}
<RelocFlags>        ::= {"RELOCS_STRIPPED" <MTS>}
                        {"RELOCS_RETAINED" <MTS>}
<Options>           ::= [<UseLocal>] [<FileOpts>] <FileSpec>
<UseLocal>          ::= <KeyString> ["," <KeyString>]
<KeyString>         ::= <Target> "_" <TagName> "_" <ToolArch>
<Target>            ::= {<Word>} {"$(TARGET)"}
<TagName>           ::= {<Word>} {"$(TOOL_CHAIN_TAG)"}
<ToolArch>          ::= {<Arch>} {"$(ARCH)"}
<FileOpts>          ::= ["Fixed" <MTS>] ["Checksum" <MTS>]
                        [<FfsAlignment>]
<FfsAlignment>      ::= "Align" <Eq> <FfsAlignmentValues> <MTS>
<FileSpec>          ::= {<SimpleFile>} {<ComplexFile>} {<SbtGuid>} {<DataFile>}
<DataFile>          ::= "{" <VarFile> "}"
<SimpleFile>        ::= <LeafSecType> [<FileOpts>] <VarFile> <EOL>
<LeafSecType>       ::= {"COMPAT16"} {"PE32"} {"PIC"} {"TE"}
                        {"FV_IMAGE"} {"RAW"} {"DXE_DEPEX"} {"UI"}
                        {"PEI_DEPEX"} {"SMM_DEPEX"} {"VERSION"}
<SbtGuid>           ::= "SUBTYPE_GUID" <MTS> <NamedGuid> <MTS> <FName> <EOL>
<VarFile>           ::= {<FilenameVariable>} {<FName>} {<Ext>}
<FName>             ::= [<PATH>] <Word> "." <Word>
<FilenameVariable>  ::= "$(INF_OUTPUT)/$(MODULE_NAME)" "." <Word>
<ComplexFile>       ::= "{" <EOL>
                        <EncapSection>*
                        <LeafSections>*
                        <TS> "}" <EOL>
<EncapSection>      ::= <TS> {<CompressSection>} {<GuidedSection>}
<CompressSection>   ::= "COMPRESS" <MTS> [<CompType>]
                        "{" [<EOL>]
                        <EncapSec>*
                        <LeafSections> <EOL>*
                        <TS> "}" <EOL>
<CompType>          ::= {"PI_STD"} {"PI_NONE"} <MTS>
<GuidedSection>     ::= "GUIDED" <MTS> <NamedGuid> <MTS> [<GAttr>]
                        "{" <EOL>
                        <EncapSec>*
                        <LeafSections>*
                        <TS> "}" <EOL>
<GAttr>             ::= [<GuidAttrPR>] [<GuidAttrASV>] [<GuidHeaderSize>]
<GuidAttrPR>        ::= "PROCESSING_REQUIRED" <Eq> <BoolType> <MTS>
<GuidAttrASV>       ::= "AUTH_STATUS_VALID" <Eq> <BoolType> <MTS>
<GuidHeaderSize>    ::= "EXTRA_HEADER_SIZE" <Eq> <Number> <MTS>
<LeafSections>      ::= <TS> {<C16Sec>} {<PeSec>} {<PicSec>} {<TeSec>}
                        {<FvSec>} {<RawSec>} {<DxeDepSec>}
                        {<UiSec>} {<VerSec>} {<PeiDepSec>}
                        {<SmmDepSec>} {<SubtypeGuidSec>}
<C16Sec>            ::= "COMPAT16" <MTS> <C16FileType> [<FileOrExt>] <EOL>
<PeSec>             ::= "PE32" <MTS> <Pe32FileType> [<FileOrExt>] <EOL>
<PicSec>            ::= "PIC" <MTS> <PicFileType> [<FileOrExt>] <EOL>
<TeSec>             ::= "TE" <MTS> <TeFileType> [<FileOrExt>] <EOL>
<RawSec>            ::= "RAW" <MTS> <RawFileType> [<FileOrExtOrPcd>] <EOL>
<DxeDepSec>         ::= "DXE_DEPEX" <MTS> <DdFileType> [<FileOrExt>] <EOL>
<SmmDepSec>         ::= "SMM_DEPEX" <MTS> <DdFileType> [<FileOrExt>] <EOL>
<UiSec>             ::= "UI" <MTS> <UiFileType> [<FileOrExt>] <EOL>
<VerSec>            ::= "VERSION" <MTS> <VerFileType> [<FileOrExt>] <EOL>
<PeiDepSec>         ::= "PEI_DEPEX" <MTS> <PdFileType>
                        [<FileOrExt>] <EOL>
<SubtypeGuidSec>    ::= "SUBTYPE_GUID" <MTS> <NamedGuid> <MTS>
                        <File> <EOL>
<FileOrExt>         ::= {<VarFile>} {<Ext>} <MTS>
<FileOrExtOrPcd>    ::= {<VarFile>} {<Ext>} {"PCD(" <PcdName> ")"}
<Ext>               ::= <FS> "." [a-zA-Z][a-zA-Z0-9]{0,}
<C16FileType>       ::= "COMPAT16" [<FfsAlignment>]
<Pe32FileType>      ::= "PE32" <MTS> [<FfsAlignment>]
                        [<XipFlag>] [<ChkReloc>]
<XipFlag>           ::= "Xip" <Eq> <BoolType> <MTS>
<ChkReloc>          ::= if (MODULE_TYPE == "SEC"
                        || MODULE_TYPE == "PEI_CORE"
                        || MODULE_TYPE == "PEIM"): [<RelocFlags>]
<PicFileType>       ::= "PIC" <MTS> [<FfsAlignment>]
<TeFileType>        ::= "TE" <MTS> [<FfsAlignment>] [<XipFlag>]
                        [<ChkReloc>]
<RawFileType>       ::= {<BinTypes>} {<AcpiFileTypes>} <MTS>
                        [<FfsAlignment>]
<BinTypes>          ::= {"BIN"} {"RAW"}
<AcpiFileTypes>     ::= {"ACPI"} {"ASL"} <MTS> ["Optional" <MTS>]
<DdFileType>        ::= {"DXE_DEPEX"} {"SMM_DEPEX"} [<DpxAlign>]
<DpxAlign>          ::= ["Optional" <MTS>] [<FfsAlignment>]
<UiFileType>        ::= {<UiFile>} {<UiString>}
<UiFile>            ::= "UI" <MTS> [<UiOpts>]
<UiString>          ::= "STRING" <Eq> <StringVal> [<FfsAlignment>]
<StringVal>         ::= {<UnicodeString>} {<QuotedString>}
                        {<NamedMacros>}
<NamedMacros>       ::= {"$(INF_VERSION)"} {"$(MODULE_NAME))"
<UiOpts>            ::= ["Optional" <MTS>] [<FfsAlignment>]
<VerFileType>       ::= {<VerFile>} {<VerString>}
<VerFile>           ::= "VERSION" <MTS> [<VerOpts>]
<VerOpts>           ::= ["Optional" <MTS>] [<BuildAlign>]
<VerString>         ::= "STRING" <Eq> <VerStringVal> <MTS> [<BuildAlign>]
<VerStringVal>      ::= {<UnicodeString>} {<QuotedString>}
                        {"$(INF_VERSION)"}
<BuildAlign>        ::= ["Optional" <MTS>] [<BuildArg>]
                        [<FfsAlignment>]
<BuildArg>          ::= "BUILD_NUM = $(BUILD_NUMBER)" <MTS>
<PdFileType>        ::= "PEI_DEPEX" <MTS> [<DpxAlign>]
<FvSec>             ::= "FV_IMAGE" <MTS> {<FvBin>} {<FvImageSection>}
<FvBin>             ::= "FV" <MTS> [<FfsAlignment>] [<FileOrExt>] <EOL>
<FvImgSection>      ::= "FV_IMAGE" <MTS> <FvImgArgs>
<FvImgArgs>         ::= "{" <EOL>
                        <MacroDefinition>*
                        [<FvAlignment>]
                        <FvAttributes>*
                        [<AprioriSection>]
                        <FileStatements>*
                        <TS> "}" <EOL>
<FvAlignment>       ::= [<TS> "FvBaseAddress" <Eq> <UINT64> <EOL>]
                        <TS> "FvAlignment" <Eq> <FvAlignmentValues> <EOL>
<FvAttributes>      ::= [<TS> "MEMORY_MAPPED" <Eq> <BoolType> <EOL>]
                        [<TS> "LOCK_CAP" <Eq> <BoolType> <EOL>]
                        [<TS> "LOCK_STATUS" <Eq> <BoolType> <EOL>]
                        [<TS> "WRITE_LOCK_CAP" <Eq> <BoolType> <EOL>]
                        [<TS> "WRITE_LOCK_STATUS" <Eq> <BoolType> <EOL>]
                        [<TS> "WRITE_ENABLED_CAP" <Eq> <BoolType> <EOL>]
                        [<TS> "WRITE_DISABLED_CAP" <Eq> <BoolType> <EOL>]
                        [<TS> "WRITE_STATUS" <Eq> <BoolType> <EOL>]
                        [<TS> "STICKY_WRITE" <Eq> <BoolType> <EOL>]
                        [<TS> "WRITE_POLICY_RELIABLE" <Eq> <BoolType> <EOL>]
                        [<TS> "READ_LOCK_CAP" <Eq> <BoolType> <EOL>]
                        [<TS> "READ_LOCK_STATUS" <Eq> <BoolType> <EOL>]
                        [<TS> "READ_ENABLED_CAP" <Eq> <BoolType> <EOL>]
                        [<TS> "READ_DISABLED_CAP" <Eq> <BoolType> <EOL>]
                        [<TS> "READ_STATUS" <Eq> <BoolType> <EOL>]
<PeiAprioriSection> ::= "APRIORI PEI" <MTS>
                        "{" <EOL>
                        <MacroDefinition>*
                        <FileStatements>* <TS> "}" <EOL>
<DxeAprioriSection> ::= "APRIORI DXE" <MTS>
                        "{" <EOL>
                        <MacroDefinition>*
                        <FileStatements>*
                        <TS> "}" <EOL>

Restrictions

FName

For BINARY ONLY content (UEFI_DRIVER and UEFI_APPLICATION .efi files) the file names specified in the SECTION element of this section must be relative to the directory identified by the WORKSPACE system environment variable (or relative to a directory listed in the PACKAGES_PATH).

Parameters

$(INF_VERSION)

This value refers to the VERSION_STRING element in the INF file's [Defines] section, not the INF_VERSION element, which is assigned based on the INF specification revision.

SUBTYPE_GUID

This is short hand notation refering to content that will be placed in a Section of type: EFI_SECTION_FREEFORM_SUBTYPE_GUID. A single

EFI_SECTION_FREEFORM_SUBTYPE_GUID section is permitted in an FFS File of type EFI_FV_FILETYPE_FREEFORM

RuleUiName

A unique single word identifier. The word "BINARY" is reserved; it is recommended that it be used for the rules that process INF modules that only contain binary content.

COMPRESS

Compression sections that use PI_STD compression do not have PROCESSING_REQUIRED = TRUE flag, it is only required for GUIDED sections.

Xip

Optional keyword for PE32 and TE leaf sections. Specifies whether the PE32 or TE section file should be rebased for eXecute-In-Place (XIP) operation when the FV has FvForceRebase = TRUE.

Valid values: TRUE, FALSE

Default: If not specified, the file will not be individually marked for XIP rebase.

The Xip, Align, and RELOCS_STRIPPED/RELOCS_RETAINED keywords may appear in any order within the PE32 or TE section definition.

Named rules with RuleOverride provide per-module granularity for XIP control.

The following table describes the rebase behavior for a file based on FvForceRebase, whether any file in the FV has Xip=TRUE, and the file's own Xip setting:

FvForceRebase Any file has Xip=TRUE This file's Xip Result
TRUE No any Rebase (legacy behavior)
TRUE Yes TRUE Rebase
TRUE Yes FALSE or not specified No rebase
FALSE any any No rebase
not specified any any See [FV] section FvForceRebase documentation

User Interface (UI) entries

There are three possible methods for specifying a User Interface string. 1) Specify the string value in the FDF file, 2) specify a plain ASCII text file that has an extension of ".ui" or 3) specify a Unicode file with an extension of ".uni" that contains a single Unicode string.

Target

Must match a target identifier in the EDK II tools_def.txt file - the first field, where fields are separated by the underscore character. Wildcard characters are not permitted.

TagName

Must match a tag name field in the EDK II tools_def.txt file - second field. Wildcard characters are not permitted

Example

[Rule.IA32.SEC]
  FILE SEC = $(NAMED_GUID) Fixed Align=32 |.efi

[Rule.Common.PEIM]
  FILE PEIM = $(NAMED_GUID) {
    TE TE |.te
    PEI_DEPEX PEI_DEPEX Optional |.Depex
    VERSION STRING    = "$(INF_VERSION)" Optional BUILD_NUM = $(BUILD_NUM)
    UI UNI_UI Optional | .uni
  }

[Rule.Common.PEI_CORE]
  FILE PEI_CORE = $(NAMED_GUID) {
    PE32     PE32   Align=Auto  Xip=TRUE   $(INF_OUTPUT)/$(MODULE_NAME).efi
    UI       STRING ="$(MODULE_NAME)" Optional
    VERSION  STRING ="$(INF_VERSION)" Optional BUILD_NUM=$(BUILD_NUMBER)
  }

[Rule.Common.PEIM.XIP]
  FILE PEIM = $(NAMED_GUID) {
    PEI_DEPEX PEI_DEPEX Optional $(INF_OUTPUT)/$(MODULE_NAME).depex
    PE32      PE32   Align=Auto  Xip=TRUE   $(INF_OUTPUT)/$(MODULE_NAME).efi
    UI       STRING="$(MODULE_NAME)" Optional
    VERSION  STRING="$(INF_VERSION)" Optional BUILD_NUM=$(BUILD_NUMBER)
  }

[Rule.Common.PEIM.NOXIP]
  FILE PEIM = $(NAMED_GUID) {
    PEI_DEPEX PEI_DEPEX Optional $(INF_OUTPUT)/$(MODULE_NAME).depex
    PE32      PE32   Align=Auto              $(INF_OUTPUT)/$(MODULE_NAME).efi
    UI       STRING="$(MODULE_NAME)" Optional
    VERSION  STRING="$(INF_VERSION)" Optional BUILD_NUM=$(BUILD_NUMBER)
  }

[Rule.Common.DXE_CORE]
  FILE DXE_CORE = $(NAMED_GUID) {
    PE32     PE32   Align=Auto              $(INF_OUTPUT)/$(MODULE_NAME).efi
    UI       STRING ="$(MODULE_NAME)" Optional
    VERSION  STRING ="$(INF_VERSION)" Optional BUILD_NUM=$(BUILD_NUMBER)
  }

[Rule.Common.PEIM.PE32]
  FILE PEIM = $(NAMED_GUID) {
    PEI_DEPEX PEI_DEPEX Optional | .dxs
    COMPRESS {
      PE32 PE32 |.efi
      VERSION UNI_VER Optional BUILD_NUM = $(BUILD_NUM) | .ver
      UI UI Optional | .ui
    }
  }